home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / openssl / engine.h < prev    next >
C/C++ Source or Header  |  2006-04-25  |  35KB  |  730 lines
  1. /* openssl/engine.h */
  2. /* Written by Geoff Thorpe (geoff@geoffthorpe.net) for the OpenSSL
  3.  * project 2000.
  4.  */
  5. /* ====================================================================
  6.  * Copyright (c) 1999-2001 The OpenSSL Project.  All rights reserved.
  7.  *
  8.  * Redistribution and use in source and binary forms, with or without
  9.  * modification, are permitted provided that the following conditions
  10.  * are met:
  11.  *
  12.  * 1. Redistributions of source code must retain the above copyright
  13.  *    notice, this list of conditions and the following disclaimer. 
  14.  *
  15.  * 2. Redistributions in binary form must reproduce the above copyright
  16.  *    notice, this list of conditions and the following disclaimer in
  17.  *    the documentation and/or other materials provided with the
  18.  *    distribution.
  19.  *
  20.  * 3. All advertising materials mentioning features or use of this
  21.  *    software must display the following acknowledgment:
  22.  *    "This product includes software developed by the OpenSSL Project
  23.  *    for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
  24.  *
  25.  * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26.  *    endorse or promote products derived from this software without
  27.  *    prior written permission. For written permission, please contact
  28.  *    licensing@OpenSSL.org.
  29.  *
  30.  * 5. Products derived from this software may not be called "OpenSSL"
  31.  *    nor may "OpenSSL" appear in their names without prior written
  32.  *    permission of the OpenSSL Project.
  33.  *
  34.  * 6. Redistributions of any form whatsoever must retain the following
  35.  *    acknowledgment:
  36.  *    "This product includes software developed by the OpenSSL Project
  37.  *    for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
  38.  *
  39.  * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40.  * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42.  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45.  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46.  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47.  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48.  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49.  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50.  * OF THE POSSIBILITY OF SUCH DAMAGE.
  51.  * ====================================================================
  52.  *
  53.  * This product includes cryptographic software written by Eric Young
  54.  * (eay@cryptsoft.com).  This product includes software written by Tim
  55.  * Hudson (tjh@cryptsoft.com).
  56.  *
  57.  */
  58.  
  59. #ifndef HEADER_ENGINE_H
  60. #define HEADER_ENGINE_H
  61.  
  62. #include <openssl/opensslconf.h>
  63.  
  64. #ifdef OPENSSL_NO_ENGINE
  65. #error ENGINE is disabled.
  66. #endif
  67.  
  68. #include <openssl/ossl_typ.h>
  69. #include <openssl/bn.h>
  70. #ifndef OPENSSL_NO_RSA
  71. #include <openssl/rsa.h>
  72. #endif
  73. #ifndef OPENSSL_NO_DSA
  74. #include <openssl/dsa.h>
  75. #endif
  76. #ifndef OPENSSL_NO_DH
  77. #include <openssl/dh.h>
  78. #endif
  79. #include <openssl/rand.h>
  80. #include <openssl/ui.h>
  81. #include <openssl/symhacks.h>
  82. #include <openssl/err.h>
  83.  
  84. #ifdef  __cplusplus
  85. extern "C" {
  86. #endif
  87.  
  88. /* Fixups for missing algorithms */
  89. #ifdef OPENSSL_NO_RSA
  90. typedef void RSA_METHOD;
  91. #endif
  92. #ifdef OPENSSL_NO_DSA
  93. typedef void DSA_METHOD;
  94. #endif
  95. #ifdef OPENSSL_NO_DH
  96. typedef void DH_METHOD;
  97. #endif
  98.  
  99. /* These flags are used to control combinations of algorithm (methods)
  100.  * by bitwise "OR"ing. */
  101. #define ENGINE_METHOD_RSA        (unsigned int)0x0001
  102. #define ENGINE_METHOD_DSA        (unsigned int)0x0002
  103. #define ENGINE_METHOD_DH        (unsigned int)0x0004
  104. #define ENGINE_METHOD_RAND        (unsigned int)0x0008
  105. #define ENGINE_METHOD_CIPHERS        (unsigned int)0x0040
  106. #define ENGINE_METHOD_DIGESTS        (unsigned int)0x0080
  107. /* Obvious all-or-nothing cases. */
  108. #define ENGINE_METHOD_ALL        (unsigned int)0xFFFF
  109. #define ENGINE_METHOD_NONE        (unsigned int)0x0000
  110.  
  111. /* This(ese) flag(s) controls behaviour of the ENGINE_TABLE mechanism used
  112.  * internally to control registration of ENGINE implementations, and can be set
  113.  * by ENGINE_set_table_flags(). The "NOINIT" flag prevents attempts to
  114.  * initialise registered ENGINEs if they are not already initialised. */
  115. #define ENGINE_TABLE_FLAG_NOINIT    (unsigned int)0x0001
  116.  
  117. /* ENGINE flags that can be set by ENGINE_set_flags(). */
  118. /* #define ENGINE_FLAGS_MALLOCED    0x0001 */ /* Not used */
  119.  
  120. /* This flag is for ENGINEs that wish to handle the various 'CMD'-related
  121.  * control commands on their own. Without this flag, ENGINE_ctrl() handles these
  122.  * control commands on behalf of the ENGINE using their "cmd_defns" data. */
  123. #define ENGINE_FLAGS_MANUAL_CMD_CTRL    (int)0x0002
  124.  
  125. /* This flag is for ENGINEs who return new duplicate structures when found via
  126.  * "ENGINE_by_id()". When an ENGINE must store state (eg. if ENGINE_ctrl()
  127.  * commands are called in sequence as part of some stateful process like
  128.  * key-generation setup and execution), it can set this flag - then each attempt
  129.  * to obtain the ENGINE will result in it being copied into a new structure.
  130.  * Normally, ENGINEs don't declare this flag so ENGINE_by_id() just increments
  131.  * the existing ENGINE's structural reference count. */
  132. #define ENGINE_FLAGS_BY_ID_COPY        (int)0x0004
  133.  
  134. /* ENGINEs can support their own command types, and these flags are used in
  135.  * ENGINE_CTRL_GET_CMD_FLAGS to indicate to the caller what kind of input each
  136.  * command expects. Currently only numeric and string input is supported. If a
  137.  * control command supports none of the _NUMERIC, _STRING, or _NO_INPUT options,
  138.  * then it is regarded as an "internal" control command - and not for use in
  139.  * config setting situations. As such, they're not available to the
  140.  * ENGINE_ctrl_cmd_string() function, only raw ENGINE_ctrl() access. Changes to
  141.  * this list of 'command types' should be reflected carefully in
  142.  * ENGINE_cmd_is_executable() and ENGINE_ctrl_cmd_string(). */
  143.  
  144. /* accepts a 'long' input value (3rd parameter to ENGINE_ctrl) */
  145. #define ENGINE_CMD_FLAG_NUMERIC        (unsigned int)0x0001
  146. /* accepts string input (cast from 'void*' to 'const char *', 4th parameter to
  147.  * ENGINE_ctrl) */
  148. #define ENGINE_CMD_FLAG_STRING        (unsigned int)0x0002
  149. /* Indicates that the control command takes *no* input. Ie. the control command
  150.  * is unparameterised. */
  151. #define ENGINE_CMD_FLAG_NO_INPUT    (unsigned int)0x0004
  152. /* Indicates that the control command is internal. This control command won't
  153.  * be shown in any output, and is only usable through the ENGINE_ctrl_cmd()
  154.  * function. */
  155. #define ENGINE_CMD_FLAG_INTERNAL    (unsigned int)0x0008
  156.  
  157. /* NB: These 3 control commands are deprecated and should not be used. ENGINEs
  158.  * relying on these commands should compile conditional support for
  159.  * compatibility (eg. if these symbols are defined) but should also migrate the
  160.  * same functionality to their own ENGINE-specific control functions that can be
  161.  * "discovered" by calling applications. The fact these control commands
  162.  * wouldn't be "executable" (ie. usable by text-based config) doesn't change the
  163.  * fact that application code can find and use them without requiring per-ENGINE
  164.  * hacking. */
  165.  
  166. /* These flags are used to tell the ctrl function what should be done.
  167.  * All command numbers are shared between all engines, even if some don't
  168.  * make sense to some engines.  In such a case, they do nothing but return
  169.  * the error ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED. */
  170. #define ENGINE_CTRL_SET_LOGSTREAM        1
  171. #define ENGINE_CTRL_SET_PASSWORD_CALLBACK    2
  172. #define ENGINE_CTRL_HUP                3 /* Close and reinitialise any
  173.                              handles/connections etc. */
  174. #define ENGINE_CTRL_SET_USER_INTERFACE          4 /* Alternative to callback */
  175. #define ENGINE_CTRL_SET_CALLBACK_DATA           5 /* User-specific data, used
  176.                                                      when calling the password
  177.                                                      callback and the user
  178.                                                      interface */
  179.  
  180. /* These control commands allow an application to deal with an arbitrary engine
  181.  * in a dynamic way. Warn: Negative return values indicate errors FOR THESE
  182.  * COMMANDS because zero is used to indicate 'end-of-list'. Other commands,
  183.  * including ENGINE-specific command types, return zero for an error.
  184.  *
  185.  * An ENGINE can choose to implement these ctrl functions, and can internally
  186.  * manage things however it chooses - it does so by setting the
  187.  * ENGINE_FLAGS_MANUAL_CMD_CTRL flag (using ENGINE_set_flags()). Otherwise the
  188.  * ENGINE_ctrl() code handles this on the ENGINE's behalf using the cmd_defns
  189.  * data (set using ENGINE_set_cmd_defns()). This means an ENGINE's ctrl()
  190.  * handler need only implement its own commands - the above "meta" commands will
  191.  * be taken care of. */
  192.  
  193. /* Returns non-zero if the supplied ENGINE has a ctrl() handler. If "not", then
  194.  * all the remaining control commands will return failure, so it is worth
  195.  * checking this first if the caller is trying to "discover" the engine's
  196.  * capabilities and doesn't want errors generated unnecessarily. */
  197. #define ENGINE_CTRL_HAS_CTRL_FUNCTION        10
  198. /* Returns a positive command number for the first command supported by the
  199.  * engine. Returns zero if no ctrl commands are supported. */
  200. #define ENGINE_CTRL_GET_FIRST_CMD_TYPE        11
  201. /* The 'long' argument specifies a command implemented by the engine, and the
  202.  * return value is the next command supported, or zero if there are no more. */
  203. #define ENGINE_CTRL_GET_NEXT_CMD_TYPE        12
  204. /* The 'void*' argument is a command name (cast from 'const char *'), and the
  205.  * return value is the command that corresponds to it. */
  206. #define ENGINE_CTRL_GET_CMD_FROM_NAME        13
  207. /* The next two allow a command to be converted into its corresponding string
  208.  * form. In each case, the 'long' argument supplies the command. In the NAME_LEN
  209.  * case, the return value is the length of the command name (not counting a
  210.  * trailing EOL). In the NAME case, the 'void*' argument must be a string buffer
  211.  * large enough, and it will be populated with the name of the command (WITH a
  212.  * trailing EOL). */
  213. #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD    14
  214. #define ENGINE_CTRL_GET_NAME_FROM_CMD        15
  215. /* The next two are similar but give a "short description" of a command. */
  216. #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD    16
  217. #define ENGINE_CTRL_GET_DESC_FROM_CMD        17
  218. /* With this command, the return value is the OR'd combination of
  219.  * ENGINE_CMD_FLAG_*** values that indicate what kind of input a given
  220.  * engine-specific ctrl command expects. */
  221. #define ENGINE_CTRL_GET_CMD_FLAGS        18
  222.  
  223. /* ENGINE implementations should start the numbering of their own control
  224.  * commands from this value. (ie. ENGINE_CMD_BASE, ENGINE_CMD_BASE + 1, etc). */
  225. #define ENGINE_CMD_BASE        200
  226.  
  227. /* NB: These 2 nCipher "chil" control commands are deprecated, and their
  228.  * functionality is now available through ENGINE-specific control commands
  229.  * (exposed through the above-mentioned 'CMD'-handling). Code using these 2
  230.  * commands should be migrated to the more general command handling before these
  231.  * are removed. */
  232.  
  233. /* Flags specific to the nCipher "chil" engine */
  234. #define ENGINE_CTRL_CHIL_SET_FORKCHECK        100
  235.     /* Depending on the value of the (long)i argument, this sets or
  236.      * unsets the SimpleForkCheck flag in the CHIL API to enable or
  237.      * disable checking and workarounds for applications that fork().
  238.      */
  239. #define ENGINE_CTRL_CHIL_NO_LOCKING        101
  240.     /* This prevents the initialisation function from providing mutex
  241.      * callbacks to the nCipher library. */
  242.  
  243. /* If an ENGINE supports its own specific control commands and wishes the
  244.  * framework to handle the above 'ENGINE_CMD_***'-manipulation commands on its
  245.  * behalf, it should supply a null-terminated array of ENGINE_CMD_DEFN entries
  246.  * to ENGINE_set_cmd_defns(). It should also implement a ctrl() handler that
  247.  * supports the stated commands (ie. the "cmd_num" entries as described by the
  248.  * array). NB: The array must be ordered in increasing order of cmd_num.
  249.  * "null-terminated" means that the last ENGINE_CMD_DEFN element has cmd_num set
  250.  * to zero and/or cmd_name set to NULL. */
  251. typedef struct ENGINE_CMD_DEFN_st
  252.     {
  253.     unsigned int cmd_num; /* The command number */
  254.     const char *cmd_name; /* The command name itself */
  255.     const char *cmd_desc; /* A short description of the command */
  256.     unsigned int cmd_flags; /* The input the command expects */
  257.     } ENGINE_CMD_DEFN;
  258.  
  259. /* Generic function pointer */
  260. typedef int (*ENGINE_GEN_FUNC_PTR)();
  261. /* Generic function pointer taking no arguments */
  262. typedef int (*ENGINE_GEN_INT_FUNC_PTR)(ENGINE *);
  263. /* Specific control function pointer */
  264. typedef int (*ENGINE_CTRL_FUNC_PTR)(ENGINE *, int, long, void *, void (*f)());
  265. /* Generic load_key function pointer */
  266. typedef EVP_PKEY * (*ENGINE_LOAD_KEY_PTR)(ENGINE *, const char *,
  267.     UI_METHOD *ui_method, void *callback_data);
  268. /* These callback types are for an ENGINE's handler for cipher and digest logic.
  269.  * These handlers have these prototypes;
  270.  *   int foo(ENGINE *e, const EVP_CIPHER **cipher, const int **nids, int nid);
  271.  *   int foo(ENGINE *e, const EVP_MD **digest, const int **nids, int nid);
  272.  * Looking at how to implement these handlers in the case of cipher support, if
  273.  * the framework wants the EVP_CIPHER for 'nid', it will call;
  274.  *   foo(e, &p_evp_cipher, NULL, nid);    (return zero for failure)
  275.  * If the framework wants a list of supported 'nid's, it will call;
  276.  *   foo(e, NULL, &p_nids, 0); (returns number of 'nids' or -1 for error)
  277.  */
  278. /* Returns to a pointer to the array of supported cipher 'nid's. If the second
  279.  * parameter is non-NULL it is set to the size of the returned array. */
  280. typedef int (*ENGINE_CIPHERS_PTR)(ENGINE *, const EVP_CIPHER **, const int **, int);
  281. typedef int (*ENGINE_DIGESTS_PTR)(ENGINE *, const EVP_MD **, const int **, int);
  282.  
  283. /* STRUCTURE functions ... all of these functions deal with pointers to ENGINE
  284.  * structures where the pointers have a "structural reference". This means that
  285.  * their reference is to allowed access to the structure but it does not imply
  286.  * that the structure is functional. To simply increment or decrement the
  287.  * structural reference count, use ENGINE_by_id and ENGINE_free. NB: This is not
  288.  * required when iterating using ENGINE_get_next as it will automatically
  289.  * decrement the structural reference count of the "current" ENGINE and
  290.  * increment the structural reference count of the ENGINE it returns (unless it
  291.  * is NULL). */
  292.  
  293. /* Get the first/last "ENGINE" type available. */
  294. ENGINE *ENGINE_get_first(void);
  295. ENGINE *ENGINE_get_last(void);
  296. /* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */
  297. ENGINE *ENGINE_get_next(ENGINE *e);
  298. ENGINE *ENGINE_get_prev(ENGINE *e);
  299. /* Add another "ENGINE" type into the array. */
  300. int ENGINE_add(ENGINE *e);
  301. /* Remove an existing "ENGINE" type from the array. */
  302. int ENGINE_remove(ENGINE *e);
  303. /* Retrieve an engine from the list by its unique "id" value. */
  304. ENGINE *ENGINE_by_id(const char *id);
  305. /* Add all the built-in engines. */
  306. void ENGINE_load_openssl(void);
  307. void ENGINE_load_dynamic(void);
  308. void ENGINE_load_cswift(void);
  309. void ENGINE_load_chil(void);
  310. void ENGINE_load_atalla(void);
  311. void ENGINE_load_nuron(void);
  312. void ENGINE_load_ubsec(void);
  313. void ENGINE_load_aep(void);
  314. void ENGINE_load_sureware(void);
  315. void ENGINE_load_4758cca(void);
  316. void ENGINE_load_cryptodev(void);
  317. void ENGINE_load_builtin_engines(void);
  318.  
  319. /* Get and set global flags (ENGINE_TABLE_FLAG_***) for the implementation
  320.  * "registry" handling. */
  321. unsigned int ENGINE_get_table_flags(void);
  322. void ENGINE_set_table_flags(unsigned int flags);
  323.  
  324. /* Manage registration of ENGINEs per "table". For each type, there are 3
  325.  * functions;
  326.  *   ENGINE_register_***(e) - registers the implementation from 'e' (if it has one)
  327.  *   ENGINE_unregister_***(e) - unregister the implementation from 'e'
  328.  *   ENGINE_register_all_***() - call ENGINE_register_***() for each 'e' in the list
  329.  * Cleanup is automatically registered from each table when required, so
  330.  * ENGINE_cleanup() will reverse any "register" operations. */
  331.  
  332. int ENGINE_register_RSA(ENGINE *e);
  333. void ENGINE_unregister_RSA(ENGINE *e);
  334. void ENGINE_register_all_RSA(void);
  335.  
  336. int ENGINE_register_DSA(ENGINE *e);
  337. void ENGINE_unregister_DSA(ENGINE *e);
  338. void ENGINE_register_all_DSA(void);
  339.  
  340. int ENGINE_register_DH(ENGINE *e);
  341. void ENGINE_unregister_DH(ENGINE *e);
  342. void ENGINE_register_all_DH(void);
  343.  
  344. int ENGINE_register_RAND(ENGINE *e);
  345. void ENGINE_unregister_RAND(ENGINE *e);
  346. void ENGINE_register_all_RAND(void);
  347.  
  348. int ENGINE_register_ciphers(ENGINE *e);
  349. void ENGINE_unregister_ciphers(ENGINE *e);
  350. void ENGINE_register_all_ciphers(void);
  351.  
  352. int ENGINE_register_digests(ENGINE *e);
  353. void ENGINE_unregister_digests(ENGINE *e);
  354. void ENGINE_register_all_digests(void);
  355.  
  356. /* These functions register all support from the above categories. Note, use of
  357.  * these functions can result in static linkage of code your application may not
  358.  * need. If you only need a subset of functionality, consider using more
  359.  * selective initialisation. */
  360. int ENGINE_register_complete(ENGINE *e);
  361. int ENGINE_register_all_complete(void);
  362.  
  363. /* Send parametrised control commands to the engine. The possibilities to send
  364.  * down an integer, a pointer to data or a function pointer are provided. Any of
  365.  * the parameters may or may not be NULL, depending on the command number. In
  366.  * actuality, this function only requires a structural (rather than functional)
  367.  * reference to an engine, but many control commands may require the engine be
  368.  * functional. The caller should be aware of trying commands that require an
  369.  * operational ENGINE, and only use functional references in such situations. */
  370. int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)());
  371.  
  372. /* This function tests if an ENGINE-specific command is usable as a "setting".
  373.  * Eg. in an application's config file that gets processed through
  374.  * ENGINE_ctrl_cmd_string(). If this returns zero, it is not available to
  375.  * ENGINE_ctrl_cmd_string(), only ENGINE_ctrl(). */
  376. int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
  377.  
  378. /* This function works like ENGINE_ctrl() with the exception of taking a
  379.  * command name instead of a command number, and can handle optional commands.
  380.  * See the comment on ENGINE_ctrl_cmd_string() for an explanation on how to
  381.  * use the cmd_name and cmd_optional. */
  382. int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
  383.         long i, void *p, void (*f)(), int cmd_optional);
  384.  
  385. /* This function passes a command-name and argument to an ENGINE. The cmd_name
  386.  * is converted to a command number and the control command is called using
  387.  * 'arg' as an argument (unless the ENGINE doesn't support such a command, in
  388.  * which case no control command is called). The command is checked for input
  389.  * flags, and if necessary the argument will be converted to a numeric value. If
  390.  * cmd_optional is non-zero, then if the ENGINE doesn't support the given
  391.  * cmd_name the return value will be success anyway. This function is intended
  392.  * for applications to use so that users (or config files) can supply
  393.  * engine-specific config data to the ENGINE at run-time to control behaviour of
  394.  * specific engines. As such, it shouldn't be used for calling ENGINE_ctrl()
  395.  * functions that return data, deal with binary data, or that are otherwise
  396.  * supposed to be used directly through ENGINE_ctrl() in application code. Any
  397.  * "return" data from an ENGINE_ctrl() operation in this function will be lost -
  398.  * the return value is interpreted as failure if the return value is zero,
  399.  * success otherwise, and this function returns a boolean value as a result. In
  400.  * other words, vendors of 'ENGINE'-enabled devices should write ENGINE
  401.  * implementations with parameterisations that work in this scheme, so that
  402.  * compliant ENGINE-based applications can work consistently with the same
  403.  * configuration for the same ENGINE-enabled devices, across applications. */
  404. int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
  405.                 int cmd_optional);
  406.  
  407. /* These functions are useful for manufacturing new ENGINE structures. They
  408.  * don't address reference counting at all - one uses them to populate an ENGINE
  409.  * structure with personalised implementations of things prior to using it
  410.  * directly or adding it to the builtin ENGINE list in OpenSSL. These are also
  411.  * here so that the ENGINE structure doesn't have to be exposed and break binary
  412.  * compatibility! */
  413. ENGINE *ENGINE_new(void);
  414. int ENGINE_free(ENGINE *e);
  415. int ENGINE_up_ref(ENGINE *e);
  416. int ENGINE_set_id(ENGINE *e, const char *id);
  417. int ENGINE_set_name(ENGINE *e, const char *name);
  418. int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
  419. int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
  420. int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
  421. int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
  422. int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
  423. int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
  424. int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
  425. int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
  426. int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
  427. int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
  428. int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
  429. int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
  430. int ENGINE_set_flags(ENGINE *e, int flags);
  431. int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
  432. /* These functions (and the "get" function lower down) allow control over any
  433.  * per-structure ENGINE data. */
  434. int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
  435.         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
  436. int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
  437.  
  438. /* This function cleans up anything that needs it. Eg. the ENGINE_add() function
  439.  * automatically ensures the list cleanup function is registered to be called
  440.  * from ENGINE_cleanup(). Similarly, all ENGINE_register_*** functions ensure
  441.  * ENGINE_cleanup() will clean up after them. */
  442. void ENGINE_cleanup(void);
  443.  
  444. /* These return values from within the ENGINE structure. These can be useful
  445.  * with functional references as well as structural references - it depends
  446.  * which you obtained. Using the result for functional purposes if you only
  447.  * obtained a structural reference may be problematic! */
  448. const char *ENGINE_get_id(const ENGINE *e);
  449. const char *ENGINE_get_name(const ENGINE *e);
  450. const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
  451. const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
  452. const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
  453. const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
  454. ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
  455. ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
  456. ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
  457. ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
  458. ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
  459. ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
  460. ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
  461. ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
  462. const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
  463. const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
  464. const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
  465. int ENGINE_get_flags(const ENGINE *e);
  466. void *ENGINE_get_ex_data(const ENGINE *e, int idx);
  467.  
  468. /* FUNCTIONAL functions. These functions deal with ENGINE structures
  469.  * that have (or will) be initialised for use. Broadly speaking, the
  470.  * structural functions are useful for iterating the list of available
  471.  * engine types, creating new engine types, and other "list" operations.
  472.  * These functions actually deal with ENGINEs that are to be used. As
  473.  * such these functions can fail (if applicable) when particular
  474.  * engines are unavailable - eg. if a hardware accelerator is not
  475.  * attached or not functioning correctly. Each ENGINE has 2 reference
  476.  * counts; structural and functional. Every time a functional reference
  477.  * is obtained or released, a corresponding structural reference is
  478.  * automatically obtained or released too. */
  479.  
  480. /* Initialise a engine type for use (or up its reference count if it's
  481.  * already in use). This will fail if the engine is not currently
  482.  * operational and cannot initialise. */
  483. int ENGINE_init(ENGINE *e);
  484. /* Free a functional reference to a engine type. This does not require
  485.  * a corresponding call to ENGINE_free as it also releases a structural
  486.  * reference. */
  487. int ENGINE_finish(ENGINE *e);
  488.  
  489. /* The following functions handle keys that are stored in some secondary
  490.  * location, handled by the engine.  The storage may be on a card or
  491.  * whatever. */
  492. EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
  493.     UI_METHOD *ui_method, void *callback_data);
  494. EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
  495.     UI_METHOD *ui_method, void *callback_data);
  496.  
  497. /* This returns a pointer for the current ENGINE structure that
  498.  * is (by default) performing any RSA operations. The value returned
  499.  * is an incremented reference, so it should be free'd (ENGINE_finish)
  500.  * before it is discarded. */
  501. ENGINE *ENGINE_get_default_RSA(void);
  502. /* Same for the other "methods" */
  503. ENGINE *ENGINE_get_default_DSA(void);
  504. ENGINE *ENGINE_get_default_DH(void);
  505. ENGINE *ENGINE_get_default_RAND(void);
  506. /* These functions can be used to get a functional reference to perform
  507.  * ciphering or digesting corresponding to "nid". */
  508. ENGINE *ENGINE_get_cipher_engine(int nid);
  509. ENGINE *ENGINE_get_digest_engine(int nid);
  510.  
  511. /* This sets a new default ENGINE structure for performing RSA
  512.  * operations. If the result is non-zero (success) then the ENGINE
  513.  * structure will have had its reference count up'd so the caller
  514.  * should still free their own reference 'e'. */
  515. int ENGINE_set_default_RSA(ENGINE *e);
  516. int ENGINE_set_default_string(ENGINE *e, const char *def_list);
  517. /* Same for the other "methods" */
  518. int ENGINE_set_default_DSA(ENGINE *e);
  519. int ENGINE_set_default_DH(ENGINE *e);
  520. int ENGINE_set_default_RAND(ENGINE *e);
  521. int ENGINE_set_default_ciphers(ENGINE *e);
  522. int ENGINE_set_default_digests(ENGINE *e);
  523.  
  524. /* The combination "set" - the flags are bitwise "OR"d from the
  525.  * ENGINE_METHOD_*** defines above. As with the "ENGINE_register_complete()"
  526.  * function, this function can result in unnecessary static linkage. If your
  527.  * application requires only specific functionality, consider using more
  528.  * selective functions. */
  529. int ENGINE_set_default(ENGINE *e, unsigned int flags);
  530.  
  531. void ENGINE_add_conf_module(void);
  532.  
  533. /* Deprecated functions ... */
  534. /* int ENGINE_clear_defaults(void); */
  535.  
  536. /**************************/
  537. /* DYNAMIC ENGINE SUPPORT */
  538. /**************************/
  539.  
  540. /* Binary/behaviour compatibility levels */
  541. #define OSSL_DYNAMIC_VERSION        (unsigned long)0x00010200
  542. /* Binary versions older than this are too old for us (whether we're a loader or
  543.  * a loadee) */
  544. #define OSSL_DYNAMIC_OLDEST        (unsigned long)0x00010200
  545.  
  546. /* When compiling an ENGINE entirely as an external shared library, loadable by
  547.  * the "dynamic" ENGINE, these types are needed. The 'dynamic_fns' structure
  548.  * type provides the calling application's (or library's) error functionality
  549.  * and memory management function pointers to the loaded library. These should
  550.  * be used/set in the loaded library code so that the loading application's
  551.  * 'state' will be used/changed in all operations. */
  552. typedef void *(*dyn_MEM_malloc_cb)(size_t);
  553. typedef void *(*dyn_MEM_realloc_cb)(void *, size_t);
  554. typedef void (*dyn_MEM_free_cb)(void *);
  555. typedef struct st_dynamic_MEM_fns {
  556.     dyn_MEM_malloc_cb            malloc_cb;
  557.     dyn_MEM_realloc_cb            realloc_cb;
  558.     dyn_MEM_free_cb                free_cb;
  559.     } dynamic_MEM_fns;
  560. /* FIXME: Perhaps the memory and locking code (crypto.h) should declare and use
  561.  * these types so we (and any other dependant code) can simplify a bit?? */
  562. typedef void (*dyn_lock_locking_cb)(int,int,const char *,int);
  563. typedef int (*dyn_lock_add_lock_cb)(int*,int,int,const char *,int);
  564. typedef struct CRYPTO_dynlock_value *(*dyn_dynlock_create_cb)(
  565.                         const char *,int);
  566. typedef void (*dyn_dynlock_lock_cb)(int,struct CRYPTO_dynlock_value *,
  567.                         const char *,int);
  568. typedef void (*dyn_dynlock_destroy_cb)(struct CRYPTO_dynlock_value *,
  569.                         const char *,int);
  570. typedef struct st_dynamic_LOCK_fns {
  571.     dyn_lock_locking_cb            lock_locking_cb;
  572.     dyn_lock_add_lock_cb            lock_add_lock_cb;
  573.     dyn_dynlock_create_cb            dynlock_create_cb;
  574.     dyn_dynlock_lock_cb            dynlock_lock_cb;
  575.     dyn_dynlock_destroy_cb            dynlock_destroy_cb;
  576.     } dynamic_LOCK_fns;
  577. /* The top-level structure */
  578. typedef struct st_dynamic_fns {
  579.     const ERR_FNS                *err_fns;
  580.     const CRYPTO_EX_DATA_IMPL        *ex_data_fns;
  581.     dynamic_MEM_fns                mem_fns;
  582.     dynamic_LOCK_fns            lock_fns;
  583.     } dynamic_fns;
  584.  
  585. /* The version checking function should be of this prototype. NB: The
  586.  * ossl_version value passed in is the OSSL_DYNAMIC_VERSION of the loading code.
  587.  * If this function returns zero, it indicates a (potential) version
  588.  * incompatibility and the loaded library doesn't believe it can proceed.
  589.  * Otherwise, the returned value is the (latest) version supported by the
  590.  * loading library. The loader may still decide that the loaded code's version
  591.  * is unsatisfactory and could veto the load. The function is expected to
  592.  * be implemented with the symbol name "v_check", and a default implementation
  593.  * can be fully instantiated with IMPLEMENT_DYNAMIC_CHECK_FN(). */
  594. typedef unsigned long (*dynamic_v_check_fn)(unsigned long ossl_version);
  595. #define IMPLEMENT_DYNAMIC_CHECK_FN() \
  596.     unsigned long v_check(unsigned long v) { \
  597.         if(v >= OSSL_DYNAMIC_OLDEST) return OSSL_DYNAMIC_VERSION; \
  598.         return 0; }
  599.  
  600. /* This function is passed the ENGINE structure to initialise with its own
  601.  * function and command settings. It should not adjust the structural or
  602.  * functional reference counts. If this function returns zero, (a) the load will
  603.  * be aborted, (b) the previous ENGINE state will be memcpy'd back onto the
  604.  * structure, and (c) the shared library will be unloaded. So implementations
  605.  * should do their own internal cleanup in failure circumstances otherwise they
  606.  * could leak. The 'id' parameter, if non-NULL, represents the ENGINE id that
  607.  * the loader is looking for. If this is NULL, the shared library can choose to
  608.  * return failure or to initialise a 'default' ENGINE. If non-NULL, the shared
  609.  * library must initialise only an ENGINE matching the passed 'id'. The function
  610.  * is expected to be implemented with the symbol name "bind_engine". A standard
  611.  * implementation can be instantiated with IMPLEMENT_DYNAMIC_BIND_FN(fn) where
  612.  * the parameter 'fn' is a callback function that populates the ENGINE structure
  613.  * and returns an int value (zero for failure). 'fn' should have prototype;
  614.  *    [static] int fn(ENGINE *e, const char *id); */
  615. typedef int (*dynamic_bind_engine)(ENGINE *e, const char *id,
  616.                 const dynamic_fns *fns);
  617. #define IMPLEMENT_DYNAMIC_BIND_FN(fn) \
  618.     int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns) { \
  619.         if (ERR_get_implementation() != fns->err_fns) \
  620.             { \
  621.             if(!CRYPTO_set_mem_functions(fns->mem_fns.malloc_cb, \
  622.                 fns->mem_fns.realloc_cb, fns->mem_fns.free_cb)) \
  623.                 return 0; \
  624.             CRYPTO_set_locking_callback(fns->lock_fns.lock_locking_cb); \
  625.             CRYPTO_set_add_lock_callback(fns->lock_fns.lock_add_lock_cb); \
  626.             CRYPTO_set_dynlock_create_callback(fns->lock_fns.dynlock_create_cb); \
  627.             CRYPTO_set_dynlock_lock_callback(fns->lock_fns.dynlock_lock_cb); \
  628.             CRYPTO_set_dynlock_destroy_callback(fns->lock_fns.dynlock_destroy_cb); \
  629.             if(!CRYPTO_set_ex_data_implementation(fns->ex_data_fns)) \
  630.                 return 0; \
  631.             if(!ERR_set_implementation(fns->err_fns)) return 0; \
  632.             } \
  633.         if(!fn(e,id)) return 0; \
  634.         return 1; }
  635.  
  636. #if defined(__OpenBSD__) || defined(__FreeBSD__)
  637. void ENGINE_setup_bsd_cryptodev(void);
  638. #endif
  639.  
  640. /* BEGIN ERROR CODES */
  641. /* The following lines are auto generated by the script mkerr.pl. Any changes
  642.  * made after this point may be overwritten when the script is next run.
  643.  */
  644. void ERR_load_ENGINE_strings(void);
  645.  
  646. /* Error codes for the ENGINE functions. */
  647.  
  648. /* Function codes. */
  649. #define ENGINE_F_DYNAMIC_CTRL                 180
  650. #define ENGINE_F_DYNAMIC_GET_DATA_CTX             181
  651. #define ENGINE_F_DYNAMIC_LOAD                 182
  652. #define ENGINE_F_ENGINE_ADD                 105
  653. #define ENGINE_F_ENGINE_BY_ID                 106
  654. #define ENGINE_F_ENGINE_CMD_IS_EXECUTABLE         170
  655. #define ENGINE_F_ENGINE_CTRL                 142
  656. #define ENGINE_F_ENGINE_CTRL_CMD             178
  657. #define ENGINE_F_ENGINE_CTRL_CMD_STRING             171
  658. #define ENGINE_F_ENGINE_FINISH                 107
  659. #define ENGINE_F_ENGINE_FREE                 108
  660. #define ENGINE_F_ENGINE_GET_CIPHER             185
  661. #define ENGINE_F_ENGINE_GET_DEFAULT_TYPE         177
  662. #define ENGINE_F_ENGINE_GET_DIGEST             186
  663. #define ENGINE_F_ENGINE_GET_NEXT             115
  664. #define ENGINE_F_ENGINE_GET_PREV             116
  665. #define ENGINE_F_ENGINE_INIT                 119
  666. #define ENGINE_F_ENGINE_LIST_ADD             120
  667. #define ENGINE_F_ENGINE_LIST_REMOVE             121
  668. #define ENGINE_F_ENGINE_LOAD_PRIVATE_KEY         150
  669. #define ENGINE_F_ENGINE_LOAD_PUBLIC_KEY             151
  670. #define ENGINE_F_ENGINE_MODULE_INIT             187
  671. #define ENGINE_F_ENGINE_NEW                 122
  672. #define ENGINE_F_ENGINE_REMOVE                 123
  673. #define ENGINE_F_ENGINE_SET_DEFAULT_STRING         189
  674. #define ENGINE_F_ENGINE_SET_DEFAULT_TYPE         126
  675. #define ENGINE_F_ENGINE_SET_ID                 129
  676. #define ENGINE_F_ENGINE_SET_NAME             130
  677. #define ENGINE_F_ENGINE_TABLE_REGISTER             184
  678. #define ENGINE_F_ENGINE_UNLOAD_KEY             152
  679. #define ENGINE_F_ENGINE_UP_REF                 190
  680. #define ENGINE_F_INT_CTRL_HELPER             172
  681. #define ENGINE_F_INT_ENGINE_CONFIGURE             188
  682. #define ENGINE_F_LOG_MESSAGE                 141
  683. #define ENGINE_F_SET_DATA_CTX                 183
  684.  
  685. /* Reason codes. */
  686. #define ENGINE_R_ALREADY_LOADED                 100
  687. #define ENGINE_R_ARGUMENT_IS_NOT_A_NUMBER         133
  688. #define ENGINE_R_CMD_NOT_EXECUTABLE             134
  689. #define ENGINE_R_COMMAND_TAKES_INPUT             135
  690. #define ENGINE_R_COMMAND_TAKES_NO_INPUT             136
  691. #define ENGINE_R_CONFLICTING_ENGINE_ID             103
  692. #define ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED         119
  693. #define ENGINE_R_DH_NOT_IMPLEMENTED             139
  694. #define ENGINE_R_DSA_NOT_IMPLEMENTED             140
  695. #define ENGINE_R_DSO_FAILURE                 104
  696. #define ENGINE_R_DSO_NOT_FOUND                 132
  697. #define ENGINE_R_ENGINES_SECTION_ERROR             148
  698. #define ENGINE_R_ENGINE_IS_NOT_IN_LIST             105
  699. #define ENGINE_R_ENGINE_SECTION_ERROR             149
  700. #define ENGINE_R_FAILED_LOADING_PRIVATE_KEY         128
  701. #define ENGINE_R_FAILED_LOADING_PUBLIC_KEY         129
  702. #define ENGINE_R_FINISH_FAILED                 106
  703. #define ENGINE_R_GET_HANDLE_FAILED             107
  704. #define ENGINE_R_ID_OR_NAME_MISSING             108
  705. #define ENGINE_R_INIT_FAILED                 109
  706. #define ENGINE_R_INTERNAL_LIST_ERROR             110
  707. #define ENGINE_R_INVALID_ARGUMENT             143
  708. #define ENGINE_R_INVALID_CMD_NAME             137
  709. #define ENGINE_R_INVALID_CMD_NUMBER             138
  710. #define ENGINE_R_INVALID_INIT_VALUE             151
  711. #define ENGINE_R_INVALID_STRING                 150
  712. #define ENGINE_R_NOT_INITIALISED             117
  713. #define ENGINE_R_NOT_LOADED                 112
  714. #define ENGINE_R_NO_CONTROL_FUNCTION             120
  715. #define ENGINE_R_NO_INDEX                 144
  716. #define ENGINE_R_NO_LOAD_FUNCTION             125
  717. #define ENGINE_R_NO_REFERENCE                 130
  718. #define ENGINE_R_NO_SUCH_ENGINE                 116
  719. #define ENGINE_R_NO_UNLOAD_FUNCTION             126
  720. #define ENGINE_R_PROVIDE_PARAMETERS             113
  721. #define ENGINE_R_RSA_NOT_IMPLEMENTED             141
  722. #define ENGINE_R_UNIMPLEMENTED_CIPHER             146
  723. #define ENGINE_R_UNIMPLEMENTED_DIGEST             147
  724. #define ENGINE_R_VERSION_INCOMPATIBILITY         145
  725.  
  726. #ifdef  __cplusplus
  727. }
  728. #endif
  729. #endif
  730.